All Databases Inside Mac - AppleEvents

AEGetEventHandler

Get an entry from an Apple event dispatch table

#include <AppleEvents.h> Apple Event Manager

OSErr AEGetEventHandler ( theAEEventClass, theAEEventID, handler,

handlerRefcon, isSysHandler );

AEEventClass theAEEVentClass ; event class to be dispatched

AEEventID theAEEventID ; event ID to be dispatched

EventHandlerProcPtr * handler ; pointer to event handler routine

long * handlerRefcon ; reference constant

Boolean isSysHandler ; TRUE =added to system coercion table

FALSE =added to application coercion

table

returns Error Code; 0 = no error

You can use the AEGetEventHandler function to get an entry from an Apple

event dispatch table.

theAEEventClass The parameter theAEEventClass is the value of the event class field

of the dispatch table entry for the desired Apple event handler, and

the parameter theAEEventID is the value of the event ID field of the

dispatch table entry for the desired Apple event handler. You can use

the typeWildCard constant for either or both of these parameters.

(For an explanation of wildcard values, see the earlier description of

the AEInstallEventHandler function.)

handler In the handler parameter, the AEGetEventHandler function

returns a pointer to the Apple event handler.

handlerRefCon In the handlerRefcon parameter, the AEGetEventHandler function

returns the reference constant that is passed by the

Apple Event Manager to the Apple event handler each time

the handler is called.

isSysHandler The isSysHandler parameter specifies the Apple event dispatch table

from which to get the handler. If isSysHandler is TRUE, the

AEGetEventHandler function returns the handler from the system

dispatch table. If isSysHandler is FALSE, AEGetEventHandler

returns the handler from your application's dispatch table.

Result codes

noErr (0) No error

errAEHandlerNotFound (-1717) No handler found for an Apple event

Notes: The parameters theAEEventClass and theAEEventID specify the event class

and event ID of the Apple events to be handled by the handler for this

dispatch table entry. For these parameters, you must provide one of the

following combinations:

• the event class and event ID of a single Apple event to be dispatched to

the handler

• the typeWildCard constant for the theAEEventClass and an event ID for

the theAEEventID, which indicates that Apple events from all event

classses whose event IDs match theAEEventID should be dispatched to

the handler

• an event class for theAEEventClass and the typeWildCard constant for

theAEEventID, which indicates that all events from the specified event

class should be dispatched to the handler

• the typeWildCard constant for both the theAEEventClass and

theAEEventID parameters, which indicates that all Apple events should

be dispatched to the handler

IMPORTANT: If you use the typeWildCard constant for either the

theAEEventClass or the theAEEventID parameter (or for both), the

corresponding handler must return the error errAEEventNotHandled if it

does not handle a particular event.

If there was already an entry in the specified Apple event dispatch table for

the same event class and event ID, it is replaced. Therefore, before

installing a handler for a particular Apple event in the system dispatch

table, use the AEGetEventHandler function to determine whether the

table already contains a handler for that event. If an entry exists,

AEGetEventHandler returns a reference constant and a pointer to that

event handler. Chain these to your event handler by providing pointers to

the previous handler and its reference constant in the handlerRefCon

parameter of AEInstallEventHandler. When your handler is finished,

use these pointers to call the previous handler. If you remove your system

handler, be sure to reinstall the chained handlers.

AEGetEventHandler returns a pointer in the handler parameters to the

handler for the Apple event dispatch table entry you specify in the

parameters theAEEventClass and theAEEventID. You can use the

typeWildCard constant for either or both of these parameters.

AEGetEventHandler will return an error unless an entry exists that

specifies typeWildCard in exactly the same way. For example, if you

specify typeWildCard in both the theAEEventClass parameter and

theAEEventID parameter, the Apple Event Manager will not return the

first handler for any event class and event ID in the dispatch table; instead,

the dispatch table must contain an entry that specifies type typeWildCard

for both the event class and the event ID, or else AEGetEventHandler will

return an error.

When an application calls a system Apple event handler, the

A5 register is set up for the calling application. For this reason, if you

provide a system Apple event handler, it should never use

A5 global variables or anything that depends on a particular context;

otherwise, the application that calls the system handler may crash.

Referenced by (6):